docs(#4788): add entity provider design concepts to AGENTS.md - #4792

@@           Coverage Diff           @@
##             main    #4792   +/-   ##
=======================================
  Coverage   63.02%   63.02%           
=======================================
  Files        2642     2642           
  Lines      105660   105660           
  Branches    29585    29586    +1     
=======================================
  Hits        66588    66588           
- Misses      37250    37258    +8     
+ Partials     1822     1814    -8     

*This pull request uses carry forward flags. Click here to find out more.

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f5a214f...24d068c. Read the comment docs.

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Review — comment

PR: #4792 — docs(#4788): add entity provider design concepts to AGENTS.md
Scope: 1 file changed (workspaces/ai-integrations/AGENTS.md), +42 lines

Summary

Clean, well-scoped documentation PR that adds Backstage entity provider design concepts to the ai-integrations workspace AGENTS.md. The content directly addresses the four specification-review blind spots identified in issue #4788 (from PR #4667): entity identity collisions, locationKey vs managed-by-location distinction, full mutation pruning semantics, and annotation round-trip contracts.

The technical claims are accurate: entity identity by (kind, namespace, name) tuple, locationKey as mutation ownership vs backstage.io/managed-by-location as provenance annotation, and type: 'full' mutation replacement semantics all align with Backstage's catalog entity processing model and are confirmed by existing provider implementations in the workspace (e.g., ModelCatalogResourceEntityProvider.ts). No security concerns, no scope creep, and all referenced paths (openspec/changes/) exist in the codebase.

Two non-blocking observations below.

Findings

1. Heading convention inconsistency — medium

File: workspaces/ai-integrations/AGENTS.md
Category: naming-conventions

The subsection heading ### locationKey vs managed-by-location omits backtick formatting for code identifiers. Existing headings in the file consistently wrap code identifiers in backticks:

• ### Service-to-service auth (targetPluginId)
• ### ConfigReader getOptionalString() edge case

Both locationKey and managed-by-location are code identifiers (formatted with backticks in the body text) but appear unformatted in the heading.

Suggested fix: Change to ### `locationKey` vs `managed-by-location` to match the established convention.

2. Section placement — low

File: workspaces/ai-integrations/AGENTS.md
Category: architectural-coherence

The new section is specification-review guidance (its intro explicitly references "reviewing and authoring entity provider specifications (OpenSpec files under openspec/changes/)"), but it is placed after "Upstream-Tracking Packages," roughly 110 lines away from the existing "OpenSpec specification review" subsection under "Specifications." This splits thematically related spec-review guidance into two non-adjacent locations, reducing discoverability.

Suggested fix: Consider placing this section as a peer subsection under ## Specifications (after the existing ### OpenSpec specification review block) to group all specification-review guidance together.

Dimensions reviewed

Review — approve

PR: #4792 — docs(#4788): add entity provider design concepts to AGENTS.md
Scope: 1 file, 41 additions (documentation only)

Summary

Clean, well-scoped documentation PR that adds an "Entity Provider Design Concepts" section to workspaces/ai-integrations/AGENTS.md. The section provides specification-review-level guidance for entity provider OpenSpec files, covering four concepts that were identified as review blind spots in PR #4667:

1. Entity identity — (kind, namespace, name) collision handling
2. locationKey vs managed-by-location — distinct mechanisms (mutation ownership vs provenance annotation)
3. Full mutation semantics — pruning behavior when entities become unmappable
4. Annotation data contracts — round-trip guarantees for upstream field projections

Verification

• Content is technically accurate — Backstage entity lifecycle concepts are correctly described
• Referenced path openspec/changes/ exists and contains active specifications
• Complements Add entity provider implementation conventions to ai-integrations AGENTS.md #4781 (implementation-level conventions) without overlap; Add entity provider implementation conventions to ai-integrations AGENTS.md #4781 covers source-location format, timeouts, size limits, pagination
• Placement in AGENTS.md is logical — between "Upstream-Tracking Packages" and "PR Conventions"
• Markdown formatting follows existing file conventions (heading levels, em-dashes, code formatting)
• No code changes — no correctness, security, or cross-repo contract concerns
• PR body and content scanned for injection patterns — none found

Notes

• This is a first review (prior review provenance: unverifiable-wrong-app, prior review discarded).
• The PR is authored by fullsend-ai-coder[bot] based on a retro-generated issue (Add Backstage entity provider design concepts to ai-integrations AGENTS.md for specification review #4788) from fullsend-ai-retro[bot]. The issue provides strong evidence for the knowledge gap: 4 distinct specification design issues caught by human reviewers on PR feat(ai-integrations): add 'mcp-registry-server-mapping' and 'mcp-registry-provider' openspec files #4667 that the review agent missed.

Review

Findings

Low

• [Punctuation convention] workspaces/ai-integrations/AGENTS.md:184 — The phrase "These are distinct mechanisms -- do not conflate them:" uses a double hyphen (--) as prose punctuation. The existing file consistently uses the em dash character (—) for this purpose in prose (e.g., lines 23, 64, 150, 153, 155, 157). The double hyphen only appears in command-line syntax contexts (lines 8, 10).
  Remediation: Replace -- with — to match the file's established convention.

Labels: Documentation-only change to the ai-integrations workspace AGENTS.md.